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Introduction 



CURSES is a Library Package for: 

□ Updating a screen with reasonable optimization, 

□ Getting input from the terminal in a screen-oriented fashion, and 

n Moving the cursor optimally from one point to another, independent of the 
two previous functions. 

These routines all use the termcap database to describe the capabilities of the ter- 
minal. 

1.1. Overview In making available the generalized terminal descriptions in rer/ncap, much 

information was made available to the programmer, but little work was taken out 
of one’s hands. CURSES helps the programmer perform the required functions, 
those of movement optimization and optimal screen updating, without doing any 
of the dirty work, and (hopefully) with nearly as much ease as is necessary to 
simply print or read things. 

The CURSES package is split into three parts: 

1 . Screen updating without user input; 

2. Screen updating with user input; and 

3 . Cursor motion optimization. 

It is possible to use the motion optimization without using either of the other 
two, and screen updating and input can be done without any programmer 
knowledge of the motion optimization, or indeed the termcap database itself. 

1.2. Terminology In this document, the following terminology is used with reasonable consistency: 



<^sun 



microsystems 



3 



B of 15 February 1986 




4 Curses Reference Manual 



Table 1-1 



Cursor Addressing 
Conventions 



1.3. Compiling Things 



1.4. Screen Updating 



Description of Terms 



Term Description 



window An internal representation containing an image of what a section of 
the terminal screen may look like at some point in time. This 
subsection can either encompass the entire terminal screen, or any 
smaller portion down to a single character within that screen. Note 
that the term window is used elsewhere in the Sun system manuals 
when describing the window management packages for driving the 
bitmapped screens. CURSES windows bear little, if any, 
resemblance to the window system concepts. 

terminal Sometimes called terminal screen. The package’s idea of what the 
terminal’s screen currently looks like, that is, what the user sees 
now. This is a special screen: 

screen This is a subset of windows which are as large as the terminal 
screen, that is, they start at the upper left hand comer and 
encompass the lower right hand comer. One of these, stdscr, is 
automatically provided for the programmer. 



The CURSES library routines address positions on a screen with the y coordinate 
first and the x coordinate second. This follows the convention of most terminals 
that address the screen in row , column order. The reader should note this con- 
vention. 

To use the CURSES library, it is necessary to have certain types and variables 
defined. Therefore, the programmer must have a line; 

tinclude <curses.h> 

at the top of the program source. The header file <curses.h> needs to include 
<sgtty.h>, so one should not do so oneself^. 

Also, compilations should have the following form: 
tutorial% cc [ C-compiler options ] filename . . . — Icurses — Itermlib 



To update the screen optimally, it is necessary for the routines to know what the 
screen currently looks like and what the programmer wants it to look like next. 
For this purpose, a data type (stmcture) named WINDOW is defined which 
describes a window image to the routines, including its starting position on the 
screen (the (y, x) coordinates of the upper left hand comer) and its size. One of 



^ The screen package also uses the Standard I/O library, so <curses,h> includes <stdio.h>. It is redundant 
(but harmless) for the programmer to include <stdio,h> too. 
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these (called curscr for current screen) is a screen image of what the terminal 
currently looks like. Another screen (called stdscr , for standard screen) is pro- 
vided by default to make changes on. 

A window is a purely internal representation. It is used to build and store a 
potential image of a portion of the terminal. It doesn’t bear any necessary rela- 
tion to what is really on the terminal screen. It is more like an array of characters 
on which to make changes. 

When one has a window which describes what some part the terminal should 
look like, the routine refresh ( ) (or wref resh ( ) if the window is not 
stdscr) is called, refresh ( ) makes the terminal, in the area covered by the 
window, look like that window. Note, therefore, that changing something on a 
window does not ‘change the terminal’ . Actual updates to the terminal screen 
are made only by calling refresh ( ) or wref resh ( ) . This allows the pro- 
grammer to maintain several different ideas of what a portion of the terminal 
screen should look like. Also, changes can be made to windows in any order, 
without regard to motion efficiency. Then, at will, the programmer can effec- 
tively say ‘make it look like this,’ and let the package worry about the best way 
to do this. 

1.5. Naming Conventions As hinted above, the routines can use several windows, but two are automatically 

given: curscr, which knows what the terminal looks like, and stdscr, which is 
what the programmer wants the terminal to look like next. The user should never 
really access curscr directly. Changes should be made to the appropriate screen, 
and then the routine refresh ( ) (or wref resh ( ) ) should be called. 

Many functions are set up to deal with stdscr as a default screen. For example, 
to add a character to stdscr , one calls addch ( ) with the desired character. If a 
different window is to be used, the routine waddch ( ) (for window-specific 
addch ( ) ) is provided^. This convention of prepending function names with a 
‘w’ when they are to be applied to specific windows is consistent. The only rou- 
tines which do not do this are those to which a window must always be specified. 

To move the cmrent (y, x) coordinates from one point to another, the routines 
move ( ) and wmove ( ) are provided. However, it is often desirable to first 
move and then perform some I/O operation. To avoid clumsiness, most I/O rou- 
tines can be preceded by the prefix ‘mv’ and the desired (y, x) coordinates then 
can be added to the arguments to the function. For example, the calls 

move (y, x) ; 

addch (ch) ; 

can be replaced by 

mvaddch(y, x, ch) ; 
and 



^ Actually, addch ( ) is really a #define macro with arguments, as are most of the "functions” which deal 
with stdscr as a default 
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wmove (win, y, x) ; 
waddch (win, ch) ; 

can be replaced by 

mvwaddch (win, y, x, ch) ; 

Note that the window description pointer {win ) comes before the added (y, x) 
coordinates. If such pointers are needed, they are always the first parameters 
passed. 
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Variables 



Many variables that describe the terminal environment are available to the pro- 
grammer. They are: 

Table 2-1 Variables to Describe the Terminal Environment 



Type 


Name 


Description 


WINDOW * 


curscr 


current version of the screen (terminal screen). 


WINDOW * 


stdscr 


standard screen. Most updates are done here. 


char * 


Def_term 


default terminal type if type cannot be 
determined 


bool 


My_term 


use the terminal specification in Def_term as 
terminal, irrelevant of real terminal type 


char * 


ttytype 


full name of the current terminal. 


int 


LINES 


number of lines on the terminal 


int 


COLS 


number of columns on the terminal 


int 


ERR 


error flag returned by routines on a fail. 


int 


OK 


error flag returned by routines when things go 
right. 



There are also several #define constants and types which are of general useful- 
ness: 

reg storage class ‘register’ (for example, reg int i;) 

bool boolean type, actually a ‘char’ (for example, bool doneit ; ) 

TRUE boolean ‘trae’ flag (1). 

FALSE boolean ‘false’ flag (0). 
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3.1. Starting up 



3.2. The Nitty-Gritty 
Output 



Programming Curses 



This is a description of how to actually use the screen package. In it, we assume 
all updating, reading, and so on, is applied to stdscr. All instructions will work 
on any window, by changing the function name and parameters as mentioned in 
chapter 1. 

To use the screen package, the routines must know about terminal characteristics, 
and the space for cursor and i'tiiycr must be allocated. These functions are per- 
formed by init scr ( ) . Since it must allocate space for the windows, it can 
overflow core when attempting to do so. On this rather rare occasion, 
init scr ( ) returns ERR. initscr ( ) must always be called before any of 
the routines which affect windows are used. If it is not, the program will core 
dump as soon as either cursor or stdscr are referenced. However, it is usually 
best to wait to call it until after you are sure you will need it, like after checking 
for startup errors. Terminal status changing routines like nl ( ) and crmode ( ) 
should be called after initscr ( ) . 

Now that the screen windows have been allocated, you can set them up for the 
run. If you want to, say, allow the window to scroll, use scrollok ( ) . If you 
want the cursor to be left after the last change, use leaveok ( ) . If this isn’t 
done, ref r esh ( ) moves the cursor to the window’s current (y, x) coordinates 
after updating it New windows of your own can be created, too, by using the 
functions newwin ( ) and subwin ( ) . delwin ( ) gets rid of old windows. If 
you wish to change the official size of the terminal by hand, just set the variables 
LINES and COLS to be what you warn, and then call initscr ( ) . This is best 
done before, but can be done either before or after, the first call to initscr ( ) , 
as it always deletes any existing stdscr and/or cursor before creating new ones. 



Now that we have set things up, we will want to actually update the terminal. 

The basic functions used to change what appears on a window are addch ( ) and 
move ( ) . addch ( ) adds a character at the current (y, x) coordinates, returning 
ERR if it would cause the window to illegally scroll, that is, printing a character 
in the lower right-hand comer of a terminal which automatically scrolls if scrol- 
ling is not allowed, move ( ) changes the current (y, x) coordinates to whatever 
you want them to be. It returns ERR if you try to move off the window when 
scrolling is not allowed. As mentioned above, you can combine the two into 
mvaddch ( ) to do both things in one fell swoop. 
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Input 



Miscellaneous 
3.3. Finishing up 



The other output functions, such as addst r ( ) and print w ( ) , all call 
addch ( ) to add characters to the window. 

After you have put on the window what you want there, when you want the por- 
tion of the terminal covered by the window to be made to look like it, you must 
call refresh ( ) . To optimize finding changes, refresh ( ) assumes that any 
part of the window not changed since the last refresh ( ) of that window has 
not been changed on the terminal, that is, that you have not refreshed a portion of 
the terminal with an overlapping window. If this is not the case, the routine 
touchwin ( ) is provided to make it look like the entire window has been 
changed, thus making refresh ( ) check the whole subsection of the terminal 
for changes. 

If you call wrefresh ( ) with cursor, it will make the screen look like cursor 
thinks it looks like. This is useful for implementing a command to redraw the 
screen in case it get messed up. 

Input is essentially a mirror image of output The complementary function to 
addch ( ) is getch ( ) which, if echo is set, calls addch ( ) to echo the charac- 
ter. Since the screen package needs to know what is on the terminal at all times, 
if characters are to be echoed, the tty must be in raw or cbreak mode. If it is 
not, getch ( ) sets it to be cbreak , reads in the character, and then resets the 
mode of the terminal to what it was before the call. 

All sorts of functions exist for maintaining and changing information about the 
windows. For the most part, the descriptions in section 5.4. should suffice. 

To do certain optimizations, and, on some terminals, to work at all, some things 
must be done before the screen routines start up. These functions are performed 
in getttmode ( ) and setterm ( ) , which are called by initscr ( ) . To 
clean up after the routines, the routine endwin ( ) is provided. It restores tty 
modes to what they were when initscr ( ) was first called. Thus, anytime 
after the call to initscr, endwin ( ) should be called before exiting. 
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Cursor Motion Optimization: Standing 

Alone 

It is possible to use the cursor optimization functions of this screen package 
without the overhead and additional size of the screen updating functions. The 
screen updating functions are designed for uses where parts of the screen are 
changed, but the overall image remains the same. Certain other programs will 
find it difficult to use these functions in this manner without considerable 
unnecessary program overhead. For such applications, such as some ‘‘crt hacks 
and optimizing cat (l)-type programs, all that is needed is the motion optimiza- 
tions. This, therefore, is a description of what goes on at the lower levels of this 
screen package. The descriptions assume a certain amount of familiarity with 
programming problems and some finer points of C. None of it is terribly 
difficult, but you should be forewarned. 

4.1. Terminal Information To use a terminal’s features to the best of a program’s abilities, you must first 

know what they are. The termcap database describes these, but a certain amount 
of decoding is necessary, and there are, of course, both efficient and inefficient 
ways of reading them in. The algorithm that curses uses is taken from vi and is 
efficient. It reads them into a set of variables whose names are two uppercase 
letters with some mnemonic value. For example, HO is a string which moves 
the cursor to the "home" position^. As there are two types of variables involving 
ttys, there are two routines. The first, gettmode ( ) , sets some variables based 
upon the tty modes accessed by gtty (2) and stty (2). The second, sett erm ( ) , 
does a larger task by reading in the descriptions from the termcap database. This 
is the way these routines are used by initscr ( ) : 

if (isatty (0) ) { 

gettmode ( ) ; 

if ( sp=getenv ( "TERM" ) ) 
setterm(sp) ; 

} 

else 

setterm(Def_term) ; 

_puts(TI) ; 

_puts (VS) ; 



^ Graphics programs designed to run on character-oriented terminals. 

* These names are identical to those variables used in the letdtermcap database to describe each capability. 
See Appendix A for a complete list of those read, and termcap{5) for a full description. 
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isatty ( ) checks to see if file descriptor 0 is a terminal^. If it is, 
gettmode ( ) sets the terminal description modes from a gtty (2). getenv ( ) 
is then called to get the name of the terminal, and that value (if there is one) is 
passed to sett erm ( ) , which reads in the variables from termcap associated 
with that terminal, getenv { ) returns a pointer to a string containing the name 
of the terminal, which we save in the character pointers/? . If isatty ( > returns 
false, the default terminal Def_term is used. The TI and V5 sequences initialize 
the terminal. _put s ( ) is a macro which uses tput s ( ) (see termcap (3X)) to 
put out a string. It is these things which endwin ( ) undoes. 

4.2. Movement 

Optimizations, or, 

Getting Over Yonder 



After using gettmode ( ) and sett erm ( ) to get the terminal descriptions, the 
function mvcur ( ) deals with this task. Its usage is simple: you simply tell it 
where you are now and where you want to go. For example 

mvcur (0, 0, LINES/2, COLS/2) 

would move the cursor from the home position (0, 0) to the middle of the screen. 
If you wish to force absolute addressing, you can use the function tgoto ( ) 
from the termcap (3X) routines, or you can tell mvcur ( ) that you are impossi- 
bly far away. For example, to absolutely address the lower left hand comer of 
the screen from anywhere just claim that you are in the upper right hand comer: 

mvcur (0, COLS-1, LINES-1, 0) 



Now that we have all this useful information, it would be nice to do something 
with it. The most difficult thing to do properly is motion optimization. When 
you consider how many different features various terminals have (tabs, backtabs, 
non-destmctive space, home sequences, absolute tabs, . . . ) you can see that 
deciding how to get from here to there can be a decidedly non-trivial task. 



^ i s at t y 0 is defined in the default C library function routines. It does a gtty (2) on the file descriptor and 
checks the return value. 
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Curses Functions 



In the following definitions, ‘t’ means that the ‘function’ is really a #def ine 
macro with arguments. This means that it will not show up in stack traces in the 
debugger, or, in the case of such functions as addch ( ) , it will show up as its 
‘w’ counterpart. The arguments are given to show the order and type of each. 
Their names are not mandatory, just suggestive. 



5.1. Output Functions 
addch and waddch — Add 
Character to Window 



addch (ch) t 
char ch; 

waddch (win, ch) 

WINDOW *win; 
char ch; 

Add the character ch on the window at the current (y, x) co-ordinates. If the 
character is a newline (An') the line is cleared to the end, and the current (y, x) 
co-ordinates are changed to the begiiming of the next line if newline mapping is 
on, or to the next line at the same x co-ordinate if it is off. A return ( Ar') moves 
to the beginning of the line on the window. Tabs (At') are expanded into spaces 
in the normal tabstop positions of every eight characters. This returns ERR if it 
would cause the screen to scroll illegally. 



addstr and waddstr — 

Add String to Window 



box — Draw Box Around 
Window 



addstr ( St) t 
char *str; 

waddstr (win, str) 

WINDOW *win; 
char *str; 

Add the string pointed to by str on the window at the current (y, x) co-ordinates. 
This returns ERR if it would cause the screen to scroll illegally. In this case, it 
puts on as much as it can. 

box (win, vert, hor) 

WINDOW *win; 
char vert, hor; 

Draws a box around the window using vert as the character for drawing the verti- 
cal sides, and hor for drawing the horizontal lines. If scrolling is not allowed. 
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and die window encompasses the lower right-hand comer of the terminal, the 
comers are left blank to avoid a scroll. 



clear and wclear — Reset 

Window clear < ) t 

wclear (win) 

WINDOW *win; 

Resets the entire window to blanks. If win is a screen, this sets the clear flag, 
which sends a dear-screen sequence on the next refresh ( ) call. This also 
moves the current (y, x) co-ordinates to (0, 0). 



clearok — Set Clear Flag 



clearok(scr, boolf) t 
WINDOW *scr; 
bool boolf; 

Sets the clear flag for the screen scr . If boolf is TRUE, this forces a dear-screen 
to be printed on the next refresh ( ) , or stop it from doing so if boolf is 
FALSE. This only works on screens, and, unlike clear ( ) , does not alter die 
contents of the screen. If scr is cursor, the next refresh ( ) call causes a 
dear-screen, even if the window passed to ref resh ( ) is not a screen. 



clrtobot and wclrtobot 

— Clear to Bottom 



clrtobot ( ) t 

wclrtobot (win) 

WINDOW *win; 

Wipes the window clear from the current (y, x) co-ordinates to the bottom. This 
does not force a dear-screen sequence on the next refresh under any cir- 
cumstances. This has no associated ‘mv’ command. 



clrtoeol and wclrtoeol 

— Clear to End of Line 



clrtoeol ( ) t 

wclrtoeol (win) 

WINDOW *win; 

Wipes the window clear from the current (y, x) co-ordinates to the end of the 
line. This has no associated ‘mv’ command. 



delch and wdelch — j i v. / % 

Delete Character 

wdelch (win) 

WINDOW *win; 

Delete the character at the current (y, x) co-ordinates. Each character after it on 
the line shifts to the left, and the last character becomes blank. 
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deleteln and wdeleteln j i 4. i , « 

-Delete Current Line deleteln () 

wdeleteln (win) 

WINDOW *win; 

Delete the current line. Every line below the current one moves up, and the bot- 
tom line becomes blank. The current (y, x) co-ordinates remains unchanged. 



erase and werase — Erase 
Window 



Erases the window to blanks without setting the clear flag. This is analagous to 
clear () , except that it never causes a dear-screen sequence to be generated on 
a refresh ( ) . This has no associated ‘mv’ command. 



erase () t 

werase (win) 
WINDOW *win; 



inschand winsch — 
Insert Character 



insch (c) 
char c; 

winsch (win, c) 

WINDOW *win; 
char c; 

Insert c at the current (y, x) co-ordinates Each character after it shifts to the right, 
and the last character disappears. This returns ERR if it would cause the screen 
to scroll illegally. 



insertlnand winsertln 

— Insert Line 



Insert a line above the current one. Every line below the current line is shifted 
down, and the bottom line disappears. The current line becomes blank, and the 
current (y, x) co-ordinates remains unchanged. This returns ERR if it would 
cause the screen to scroll illegally. 

move and wmove — Move . . . 

move (y, x) t 

int y, x; 

wmove (win, y, x) 

WINDOW *win; 
int y, x; 

Change the current (y, x) co-ordinates of the window to (y, x). This returns ERR 
if it would cause the screen to scroll illegally. 



insertln ( ) 

winsertln (win) 
WINDOW *win; 
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overlay — Overlay 
Windows 



overwrite — Overwrite 
Windows 



printw and wprintw — 

Print to Window 



refresh and wrefresh — 

Synchronize 



standout and wstandout 

— Put Characters in Standout 
Mode 



overlay <winl, win2) 

WINDOW *winl , *win2 ; 

Overlay winl on win2 . The contents of winl , insofar as they fit, are placed on 
wiriZ at their starting (y, x) co-ordinates. This is done non-destructively, that is, 
blanks on winl leave the contents of the space on win2 untouched. 



overwrite (winl, win2) 

WINDOW *winl, *win2; 

Overwrite winl on win2 . The contents of winl , insofar as they fit, are placed on 
wiriZ at their starting (y, x) co-ordinates. This is done destructively, that is, 
blanks on winl become blank on winZ . 

printw (fmt, argl, arg2, ...) 
char *fmt; 

wprintw(win, fmt, argl, arg2, ...) 

WINDOW *win; 
char *fmt; 

Performs a pr intf ( ) on the window starting at the current (y, x) co-ordinates. 
It uses addstr ( ) to add the string on the window. It is often advisable to use 
the field width options of print f ( ) to avoid leaving things on the window 
from earlier calls. This returns ERR if it would cause the screen to scroll ille- 
gally. 



refresh!) t 

wrefresh (win) 

WINDOW +win; 

Synchronize the terminal screen with the desired window. If the window is not a 
screen, only that part covered by it is updated. This returns ERR if it would cause 
the screen to scroll illegally. In this case, it updates whatever it can without caus- 
ing the scroll. 

standout ( ) t 

wstandout (win) 

WINDOW *win; 

standend ( ) t 

wstandend (win) 

WINDOW *win; 

Start and stop putting characters onto win in standout mode, standout ( ) 
causes any characters added to the window to be put in standout mode on the ter- 
minal (if it has that capability), standend ( ) stops this. The sequences SO 
and SE (or US and UE if they are not defined) are used (see Appendix A). 
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5.2. Input Functions 

crmode and nocrmode — 

Set or Unset from cbreak 
mode 



echo and noecho — Turn 
Echo On or Off 



getch and wgetch — Get 

Character from Terminal 



getstr and wgetstr — 

Get String from Terminal 



raw and noraw — Turn 
Raw Mode On or Off 



crmode ( ) t 
nocrmode ( ) t 

Set or unset the terminal to/from cbreak mode. 

echo ( ) t 
noecho ( ) t 

Sets the terminal to echo or not echo characters. 



getch ( ) t 

wgetch (win) 

WINDOW *win; 

Gets a character from the terminal and (if necessary) echos it on the window. 
This returns ERR if it would cause the screen to scroll illegally. Otherwise, the 
character gotten is returned. If noecho has been set, then the window is left unal- 
tered. In order to retain control of the terminal, it is necessary to have one of 
noecho, cbreak, or rawmode set. If you do not set one, whatever routine you call 
to read characters sets cbreak for you, and then resets to the original mode when 
finished. 



getstr ( St) t 
char *str; 

wgetstr (win, str) 

WINDOW *win; 
char *str; 

Get a string through the window and put it in the location pointed to by str , 
which is assumed to be large enough to handle it. It sets tty modes if necessary, 
and then calls getch ( ) (or wgetch ( win ) ) to get the characters needed to fill 
in the string until a newline or EOF is encountered. The newline stripped olf the 
string. This returns ERR if it would cause the screen to scroll illegally. 



raw ( ) t 
noraw () t 

Set or unset the terminal to/from raw mode. On version 7 UNDCt systems, this 
also turns off newline mapping (see nl ( ) ). 



t UNIX is a trademark of AT&T Bell Laboratories. 
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scanwand wscanw — Read 
String from Terminal 



scanw(fmt, argl, arg2, ...) 
char *fmt; 

wscanw(win, fmt, argl, arg2, ...) 
WINDOW *win; 
char *frat; 



Perform a scanf ( ) through the window using^r . It does this using consecu- 
tive getch ( ) ’s (or wgetch ( win ) ’s). This returns ERR if it would cause the 
screen to scroll illegally. 



5.3. Miscellaneous Functions 
delwin — Delete a Window 



delwin (win) 

WINDOW *win; 

Deletes the window from existence. All resources are freed for future use by 
calloc(3). If a window has a subwin ( ) allocated window inside of it, delet- 
ing the outer window does not affect the subwindow, even though this does 
invalidate it. Therefore, subwindows should be deleted before their outer win- 
dows are. 



endwin — Finish up Window 
Routines 



endwin ( ) 

Finish up window routines before exit. This restores the terminal to the state it 
was in before init scr ( ) (or gettmode ( ) and setterm ( ) ) was called, 
endwin should always be called before exiting, endwin does not itself exit — 
this is especially useful for resetting tty stats when trapping rubouts via sig- 
nal(2). 



getyx — Get Current 
Coordinates 



getyx (win, y, x) t 
WINDOW *win; 
int y, x; 

Puts the current (y, x) co-ordinates of win in the variables y and x . Since it is a 
macro, not a function, you do not pass the address of y and x . 



inch and winch — Get 
Character at Current 
Coordinates 



inch ( ) t 

winch (win) t 
WINDOW *win; 

Returns the character at the current (y, x) co-ordinates on the given window. 
This does not make any changes to die window. This has no associated ‘mv’ 
command. 



init scr — Initialize Screen 
Routines 



initscr ( ) 

Initialize the screen routines. This must be called before any of the screen rou- 
tines are used. It initializes the terminal-type data and such, and without it, none 
of the routines can operate. If standard input is not a tty, it sets the specifications 
to the terminal whose name is pointed to by Def term (initialy "dumb"). If the 
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leaveok — Set Leave 
Cursor Flag 



boolean My term is true, Def term is always used. 

leaveok (win, boolf) t 
WINDOW *win; 
bool boolf; 

Sets the boolean flag for leaving the cursor after the last change. If boolf is 
TRUE, the cursor is left after the last update on the terminal, and the current 
(y, x) co-ordinates for win are changed accordingly. If it is FALSE, it is moved 
to the current (y, x) co-ordinates. This flag (initially FALSE) retains its value 
until changed by the user. 

For example, say the current position is (0, 0) and we change the character at 
position (5, 10) in the window. After calling refresh ( ) , the cursor is either 
moved to position (5, 10) (if the flag is TRUE) or the cursor is left at position 
(0, 0) (if the flag is FALSE). 



longname — Get Full Name , ^ \ 

^ . longname (termbuf, name) 

of Terminal char *termbuf, *name; 

Fills in name with the long (full) name of the terminal described by the termcap 
entry in termbuf. It is generally of little use, but is nice for telling the user in a 
readable format what terminal we think he has. The long name is also available 
in the global variable ttytype . Termbuf is usually set via the termlib routine 
tgetent ( ) . 



mvwin — Move Home 
Position of Window 



mvwin (win, y, x) 

WINDOW *win ; 
int y, x; 

Move the home position of the window win from its current starting coordinates 
to (y, X ). If that would put part or all of the window off the edge of the terminal 
screen, mvwin ( ) returns ERR and does not change anything. 



newwin — Create a New 
Window 



WINDOW * 

newwin (lines, cols, begin_y, begin_x) 
int lines, cols, begin_y, begin_x; 

Create a new window with lines lines and cols columns starting at position 
(begin_y, beginjc ). If either lines or cols is 0 (zero), that dimension is set to 
(LINES - begin_y ) or (COLS - beginjc ) respectively. Thus, to get a new win- 
dow of dimensions LINES x COLS , use newwin ( 0 , 0 , 0 , 0 ) . 



nl and nonl — Turn ^ . 

Newline Mode On or Off ^ 

nonl ( ) t 

Set or unset the terminal to/from nl mode, that is, start/stop the system from map- 
ping <carriage-return> to <line-feed>. If the mapping is not done, 
refresh ( ) can do more optimization, so it is recommended, but not required, 
that it be turned off. 



•#sun 

XT microsystems 



B of 15 February 1986 




28 Curses Reference Manual 



scrollok — Set Scroll Flag 
for Window 



t ouchwin — Indicate 
Window Has Been Changed 



subwin — Create a 
Subwindow 



unctrl — Return 
Representation of Character 



5.4. Details 

gettmode — Get tty 

Statistics 

mvcur — Move Cursor 



scrollok (win, boolf) t 
WINDOW *win; 
bool boolf; 

Set the scroll flag for the given window. If boolf is FALSE, scrolling is not 
allowed. This is its default setting. 



t ouchwin (win) 

WINDOW *win; 

Make it appear that the every location on the window has been changed. This is 
usually only needed for refreshes with overlapping windows. 

WINDOW * 

subwin (win, lines, cols, begin_y, begin_x) 

WINDOW *win ; 

int lines, cols, begin_y, begin_x; 

Create a new window with lines lines and cols columns starting at position 
{begin_y, begin_x) in the middle of the window win. This means that any 
change made to either window in the area covered by the subwindow is made on 
both windows, begin jy, beginjc are specified relative to the overall screen, not 
the relative (0, 0) of win . If either lines or cols is 0 (zero), that dimension is set 
to (LINES — begin jy) or (COLS - begin x) respectively. 



unctrl (ch) t 
char ch; 

This is actually a debug function for the library, but it is of general usefulness. It 
returns a string which is a representation of ch . Control characters become their 
upper-case equivalents preceded by a ~ (circumflex character). Other letters 
stay just as they are. 



gettmode ( ) 

Get the tty stats. This is normally called by initscr ( ) . 



mvcur (lasty, lastx, newy, newx) 
int lasty, lastx, newy, newx; 

Moves the terminal’s cursor from (lasty, lastx) to (newy, newx) in an approxima- 
tion of optimal fashion. It is possible to use this optimization without the benefit 
of the screen routines. With the screen routines, this should not be called by the 
user, move ( ) and refresh ( ) should be used to move the cursor position, so 
that the routines know what’s going on. 
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scroll — Scroll Window 



scroll (win) 

WINDOW *win; 

Scroll the window upward one line. This is normally not used by the user. 



savetty and resetty — 

Save and Reset tty Flags 



savetty ( ) t 
resetty () t 

savetty ( ) saves the current tty characteristic flags, resetty ( ) restores 
them to what savetty ( ) stored. These functions are performed automatically 
by initscr ( ) and endwin ( ) . 



sett erm — Set Terminal 
Characteristics 



setterm(name) 
char *name; 

Set the terminal characteristics to be those of the terminal named name . This is 
normally called by initscr ( ) . 



tstp 



tstp( ) 

If the new tty (4) driver is in use, this function saves the current tty state and then 
puts the process to sleep. AJVhen the process gets restarted, it restores the tty state 
and then calls wref resh ( cursor ) to redraw the screen, initscr ( ) sets 
the signal SIGTSTP to trap to this routine. 
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A 



Capabilities from termcap 



A.I. Disclaimer The description of terminals is a difficult business, and we only attempt to sum- 

marize the capabilities here. For a full description see the termcap(5) manual 
pages. 

A.2. Overview Capabilities from termcap are of three kinds: string valued options, numeric 

valued options, and boolean options. The string valued options are the most 
complicated, since they may include padding information. 

Intelligent terminals often require padding on intelligent operations at high (and 
sometimes even low) speed. This is specified by a number before the string in 
the capability, and has meaning for the capabilities which have a P at the front of 
their comment. This normally is a number of milliseconds to pad the operation. 
In the current system which has no true programmable delays, we do this by 
sending a sequence of pad characters (normally nulls, but can be changed — 
specified by PC ). In some cases, the pad is better computed as some number of 
milliseconds times the number of affected lines (to the bottom of the screen usu- 
ally, except when terminals have insert modes which will shift several lines.) 
This is specified as, for example, 12* before the capability, to say 12 mil- 
liseconds per affected whatever (currently always line). Capabilities where this 
makes sense say P*. 
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A.3. Variables Set By 
settermO 

Table A- 1 Variables Set by setterm( ) 



Type 




Name 


Pad 


Description 


char 


* 


AL 


PHe 


Add new blank Line 


bool 




AM 




Automatic Margins 


char 


He 


BC 




Back Cursor movement 


bool 




BS 




Backspace works 


char 


* 


BT 


P 


Back Tab 


bool 




CA 




Cursor Addressable 


char 


He 


CD 


PHe 


Clear to end of Display 


char 


He 


CE 


P 


Clear to End of line 


char 


He 


CL 


PHe 


CLear screen 


char 


He 


CM 


P 


Cursor Motion 


char 


He 


DC 


PHe 


Delete Character 


char 


He 


DL 


PHe 


Delete Line sequence 


char 


He 


DM 




Delete Mode (enter) 


char 


He 


DO 




DOwn line sequence 


char 


He 


ED 




End Delete mode 


bool 




EO 




can Erase Overstrikes with ' ' 


char 


He 


El 




End Insert mode 


char 


He 


HO 




HOme cursor 


bool 




HZ 




HaZeltine " braindamage 


char 


He 


IC 


P 


Insert Character 


bool 




IN 




Insert-Null blessing 


char 


He 


IM 




enter Insert Mode (IC usually set, too) 


char 


He 


IP 


p* 


Pad after char Inserted using IM+IE 


char 


He 


LL 




quick to Last Line, column 0 


char 


He 


MA 




Ctrl character MAp for cmd mode 


bool 




MI 




can Move in Insert mode 


bool 




NC 




No Cr: \r sends \r\n then eats \n 


char 


He 


ND 




Non-Destructive space 


bool 




OS 




OverStrike works 


char 




PC 




Pad Character 


char 


H: 


SE 




Standout End (may leave space) 


char 


He 


SF 


P 


Scroll Forwards 


char 


He 


SO 




Stand Out begin (may leave space) 


char 


He 


SR 


P 


Scroll in Reverse 


char 


He 


TA 


P 


TAb (not T or with padding) 


char 


He 


TE 




Terminal address enable Ending sequence 


char 


He 


TI 




Terminal address enable Initialization 


char 


He 


UC 




Underline a single Character 


char 


He 


UE 




Underline Ending sequence 


bool 




UL 




UnderLining works even though !OS 
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T able A- 1 Variables Set by setterm ( ) — Continued 



Type 


Name 


Pad Description 


char * 


UP 


UPline 


char * 


US 


Underline Starting sequence^ 


char * 


VB 


Visible Bell 


char * 


VE 


Visual End sequence 


char * 


VS 


Visual Start sequence 


bool 


XN 


a Newline gets eaten after wrap 



Names starting withX are reserved for severely nauseous glitches 



A.4. Variables Set By 
gettmodeO 

Table A-2 Variables Set By gettmode( ) 



type 


name 


description 


bool 


NONL 


Term can’t hack linefeeds doing a CR 


bool 


GT 


Gtty indicates Tabs 


bool 


UPPERCASE 


Terminal generates only uppercase letters 



US and UE, if they do not exist in the termcap entry, are copied from SO and SE in settermQ 
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B 



The WINDOW structure 



The WINDOW structure is defined as follows: 

# define WINDOW struct win st 



struct _win_st { 

short _cury, _curx; 

short _maxy, _maxx; 

short _begy, __begx; 

short __flags; 

bool _clear; 

bool _leave; 

bool _scroll; 

char 

short *___firstch; 

short *_lastch; 

}; 



# 


define 


_SUBWIN 


01 


# 


define 


_ENDLINE 


02 


# 


define 


_FULLWIN 


04 


# 


define 


_SCROLLWIN 


010 


# 


define 


STANDOUT 


0200 



_cury and _curx are the current (y, x) coordinates for the window. New charac- 
ters added to the screen are added at this point, jnaxy and jnaxx are the max- 
imum values allowed for {j:ury,j:urx\ _begy and Jyegx are the starting (y, x) 
coordinates on the terminal for the window, that is, the window’s home. _yury , 
j:urx , jnaxy , and jnaxx are measured relative to ijt>egy, _J>egx ), not the 
terminal’s home. 



jclear tells if a dear-screen sequence is to be generated on the next 
refresh () call. This is only meaningful for screens. The initial dear-screen 
for the first refresh ( ) call is generated by initially setting clear to be TRUE 
for curscr , which always generates a dear-screen if set, irrelevant of the dimen- 
sions of the window involved. Jeave is TRUE if the current (y , x) coordinates 
and the cursor are to be left after the last character changed on the terminal, or 
not moved if there is no change. _scroll is TRUE if scrolling is allowed. 



All variables not normally accessed directly by the user are named with an initial to avoid conflicts 
with the user’s variables. 



»sun 

XT microsystems 



39 



B of 15 February 1986 




40 Curses Reference Manual 



is a pointer to an array of lines which describe the terminal. Thus: 

_y[i] 

is a pointer to the i th line, and 
_y[i] [j] 

is the y th character on the i th line. 

Jlags can have one or more values or’d into it. _SUBWIN means that the win- 
dow is a subwindow, which indicates to delwin ( ) that the space for the lines 
is not to be freed. _ENDLINE says that the end of the line for this window is 
also the end of a screen. _FULLWIN says that this window is a screen. 
_SCR0LLWIN indicates that the last character of this screen is at the lower 
right-hand comer of the terminal; that is, if a character was put there, the terminal 
would scroll. _STANDOUT says that all characters added to the screen are in 
standout mode. 
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c 



Examples 



Here is a simple example of how to use the package. 

This example (twinkle) is intended to demonstrate the basic structure of a pro- 
gram using the screen updating sections of the package. 

This is a moderately simple program which prints pretty patterns on the screen 
that might even hold your interest for 30 seconds or more. It switches between 
patterns of asterisks, putting them on one by one in random order, and then tak- 
ing them off in the same fashion. 

# include <curses.h> 

# include <signal.h> 

/* 

* the idea for this program was a product 

* of the imagination of Kurt Schoens . Not 

* responsible for minds lost or stolen. 

*/ 

# define NCOLS 80 

# define NLINES 24 

# define MAXPATTERNS 4 

struct Iocs { 

char y, x; 

}; 



typedef struct Iocs LOGS; 

LOGS Layout [NGOLS * NLINES]; /* current board layout */ 

int Pattern, /* current pattern number +/ 

Numstars; /* number of stars in pattern */ 

main ( ) { 

char *getenv(); 

int die ( ) ; 

srand(getpid() ) ; /* initialize random sequence */ 
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initscr 0 ; 

signal (SIGINT^ die) ; 
noecho ( ) ; 
nonl ( ) ; 

leaveok (stdscr^ TRUE) ; 
scrollok (stdscr, FALSE) ; 

for (;;) { 

makeboardO ; 
puton ) ; 
puton (' ' ) ; 

1 

} 

/* 

* On program exit, move the cursor to the lower 

* left corner by direct addressing, since current 

* location is not guaranteed. We lie and say we 

* used to be at the upper right corner to guarantee 

* absolute addressing. 

*/ 

dieO { 

signal (SIGINT, SIG_IGN) ; 
mvcur(0, COLS-1, LINES-1, 0) ; 
endwin ( ) ; 
exit ( 0 ) ; 



/* make the board setup */ 
/* put on '*'s */ 

/* cover up with ^ 's */ 



/* 

* Make the current board setup. It picks a random 

* pattern and calls ison() to determine if the 

* character is on that pattern or not. 

*/ 

makeboardO { 

reg int y, x; 

reg LOGS *lp; 

Pattern = randO % MAXPATTERNS; 

Ip = Layout; 

for (y = 0; y < NLINES; y++) 

for (x = 0; X < NCOLS; x++) 
if (ison(y, x) ) { 

lp->y = y; 
lp++->x = x; 

} 

Numstars = Ip - Layout; 

} 

/* 

* Return TRUE if (y, x) is on the current pattern. 
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*/ 

ison(y^ x) 
reg int y, x; { 

switch (Pattern) { 

case 0 : /* alternating lines */ 

return ! (y & 01) ; 
case 1: /* box ♦/ 

if (X >= LINES && y >= NCOLS) 
return FALSE; 

if (y < 3 I I y >= NLINES - 3) 
return TRUE; 

return (x < 3 | | x >= NCOLS - 3) ; 
case 2: /* holy pattern! ♦/ 

return ( (x + y) & 01) ; 
case 3: /♦ bar across center */ 

return (y >= 9 && y <= 15); 

} 

h NOTRE ACHED */ 

} 

put on (ch) 

reg char ch; { 

reg LOCS *lp; 

reg int r; 

reg LOCS *end; 

LOCS temp; 

end = &Layout [Numstars] ; 
for (Ip = Layout; Ip < end; lp++) { 

r = randO % Numstars; 
temp = *lp; 

*lp = Layout [r]; 

Layout [r] = temp; 

} 

for (Ip = Layout; Ip < end; lp++) { 

mvaddch (lp->y, lp->x, ch) ; 
refresh () ; 

} 

} 
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